Skip to content

feat(gateway): 实现 GW-01 契约层，包含帧结构定义、校验逻辑及单元测试#199

Merged
phantom5099 merged 2 commits into
1024XEngineer:mainfrom
pionxe:feat/gw-01-gateway-contract
Apr 9, 2026
Merged

feat(gateway): 实现 GW-01 契约层，包含帧结构定义、校验逻辑及单元测试#199
phantom5099 merged 2 commits into
1024XEngineer:mainfrom
pionxe:feat/gw-01-gateway-contract

Conversation

@pionxe

@pionxe pionxe commented Apr 8, 2026

Copy link
Copy Markdown
Collaborator

概述

本 PR 实现了 GW-01 任务，新增了一个独立的 internal/gateway 契约模块。该模块目前仅包含定义与协议，尚未与应用层（app）或运行层（runtime）进行耦合关联。

包含内容

  • 新增网关协议帧结构 (Protocol Frame Schema)：
    • 定义了 FrameType（帧类型）、FrameAction（帧动作）、MessageFrame（消息帧）、FrameError（帧错误）。
    • 新增多模态输入 DTO（数据传输对象）：InputPart、Media。
  • 新增网关本地运行时接口契约 (Runtime Port Contracts)：
    • 实现了与 internal/runtime 或 internal/provider 解耦的接口定义：Gateway、RuntimePort。
    • 定义了相关 DTO：RunInput、CompactInput、CompactResult、RuntimeEvent、Session（会话）、SessionSummary（会话摘要）。
  • 新增标准的网关错误码及辅助工具：
    • 包含：invalid_frame（非法帧）、invalid_action（非法动作）、invalid_multimodal_payload（非法多模态负载）、missing_required_field（缺失必填项）、unsupported_action（不支持的动作）、internal_error（内部错误）。
  • 新增帧校验器 (Frame Validator)：
    • 实现 ValidateFrame(frame MessageFrame) *FrameError 函数。
    • 支持对请求/动作的合法性检查、运行输入要求检查、多模态负载检查以及特定动作下的必填字段检查。

影响范围安全性 (Scope Safety)

  • 未修改应用启动（bootstrap）的相关逻辑。
  • 未集成具体的运行时（runtime）或服务提供商（provider）。
  • 对当前主链路的执行路径无任何行为改变。

测试情况

  • 表格驱动测试：针对帧、动作及必填字段进行了校验测试。
  • 多模态测试：验证了多模态负载的合法性。
  • 序列化测试：针对 MessageFrame 进行了 JSON 序列化的双向转换（Round-trip）测试。
  • 错误码测试：验证了标准错误码的正确性。

验证方式

  • 执行网关模块测试：go test ./internal/gateway/...
  • 执行全项测试：go test ./...

关联任务

@pionxe pionxe added the enhancement New feature or request label Apr 8, 2026
@codecov

codecov Bot commented Apr 8, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 84.21053% with 18 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/gateway/validate.go 82.52% 12 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!

@pionxe
feat(gateway): 实现 GW-01 契约层（定义协议帧、接口与校验逻辑）
48e619d 
实现了独立的 internal/gateway 模块，包含：
1. 协议帧 (MessageFrame) 及多模态数据结构
2. Runtime 交互接口契约 (Port Contracts)
3. 自动化帧校验器及标准错误处理机制
4. 完整的单元测试覆盖

Ref: 1024XEngineer#196, 1024XEngineer#198
@pionxe pionxe force-pushed the feat/gw-01-gateway-contract branch from b88f683 to 48e619d Compare April 8, 2026 13:04
@phantom5099

phantom5099 commented Apr 9, 2026

Copy link
Copy Markdown
Collaborator

contracts.go:71
当前 runtime 已经有完整的权限审批闭环：工具命中 ask 策略时会发出 permission_request / permission_resolved 事件，并且需要通过 ResolvePermission(...) 回传审批结果。但这份 gateway 契约里只有 run、compact、cancel 这些请求动作，既没有“提交权限决策”的协议动作，RuntimePort 里也没有对应方法。等以后真正把 gateway 接到现有 runtime 上时，权限型工具调用只能发起询问，却没有办法继续执行。

contracts.go:48
SessionMessage 目前只保留了 role、content、tool_call_id 和 is_error，但当前会话历史里还会保存 assistant 侧的 tool_calls 元数据。这样一来，如果通过 gateway 的 LoadSession 读取一段“assistant 计划调用工具”的历史，客户端虽然还能看到后续工具结果，但看不到最初 assistant 发起了哪些工具调用、参数是什么，整段会话语义就不完整了。也就是说，这个 session 契约相比现有 runtime/session 模型是有信息损失的

@pionxe

pionxe commented Apr 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

contracts.go:71 当前 runtime 已经有完整的权限审批闭环：工具命中 ask 策略时会发出 permission_request / permission_resolved 事件，并且需要通过 ResolvePermission(...) 回传审批结果。但这份 gateway 契约里只有 run、compact、cancel 这些请求动作，既没有“提交权限决策”的协议动作，RuntimePort 里也没有对应方法。等以后真正把 gateway 接到现有 runtime 上时，权限型工具调用只能发起询问，却没有办法继续执行。

contracts.go:48 SessionMessage 目前只保留了 role、content、tool_call_id 和 is_error，但当前会话历史里还会保存 assistant 侧的 tool_calls 元数据。这样一来，如果通过 gateway 的 LoadSession 读取一段“assistant 计划调用工具”的历史，客户端虽然还能看到后续工具结果，但看不到最初 assistant 发起了哪些工具调用、参数是什么，整段会话语义就不完整了。也就是说，这个 session 契约相比现有 runtime/session 模型是有信息损失的

已修复

@phantom5099 phantom5099 merged commit fcd1d06 into 1024XEngineer:main Apr 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@pionxe @phantom5099